--------------------------------------------
APPR
Automated Profiling & Performance Regression
README
=============================================

APPR is a framework and set of scripts for automating performance profiling
of the OpenOffice.org application. It provides mechanisms to start up
OpenOffice.org, execute a set of workloads using starBasic, synchronizing
data gathering from multiple tools and visualizing the results.

APPR is intended for use by Openoffice.org developer and QA community.

APPR is distributed as a package available from various places.
It is also part of the OpenOffice.org build CVS.

Detailed information about APPR usage and design is available in documents
distributed with this package. This file provides a brief introduction.

Pre-requisite packages
=======================
This version of APPR has been validated on Novell Linux Desktop 9 FCS9. Additional
packages/modules for using APPR are listed as follows:
1. VTune
	It is required for using the VTune hook service in APPR. VTune is a commercial
	performance tool developed by Intel.

2. miniXML Perl module
	It is required by result analysis and visualization. It can be got from
	http://minixml.psychogenic.com/download.html

3. SVG Perl module
	It is required by result analysis and visualization. It can be got from
	http://search.cpan.org/~ronan/SVG-2.28/

Quick Install Steps
====================

1. Install OpenOffice Macro
2. Rebuild OpenOffice with APPR hook patch (instrumentation) enabled
3. Execute the APPR tool

Directory Layout & Files
=========================
appr
   The main invocation and control script

appr_hook
   Hook controller, tracks and invokes profiling utilities

appr_make
   Builds utilities from src/ and puts them in utils/

appr_hook.d/
   Contains hook service executables to invoke profiling instruments
   Includes monitor.hook, strace.hook, vtune.hook

src/
   Contains C/C++ source code for APPR utilities

src/pload.c, src/makefile
   Load/Pause utility which synchronizes profiling

src/monitor/monitor.c, src/monitor/makefile
   System performance monitor - gets CPU, memory & disk stats

src/appr_hook/
   Contains the functions and daemon to allow fine level profiling control
   from within Openoffice source code. Also includes patches to OpenOffice
   source for enabling this functionality.

starBASIC/
   Contains macro files.
   Actions.xba has the OO macro scripts, script.xlb has registration metadata

Installing OpenOffice Macros
=============================
Start OpenOffice.org and use "Tools | Macros" menu to add the included
starBasic scripts appropriately. Detailed instructions, with pictures,
can be found in the User Guide in the APPR tree at:

     ./docs/APPR-User-Guide.odt

Rebuild OpenOffice with APPR hook patch (instrumentation) enabled
===========================================
To enable VTune control and tool synchronization through OpenOffice RTL
logging, you need to apply some patches and rebuild OpenOffice.

	a) Extract OpenOffice source code

	b) Apply APPR hook patch by invoking the patch apply script shipped with APPR
		./src/appr_hook/ooo-patch/apply.sh <OO_DIR>

	where, <OO_DIR> should be the parent direcotry of sal module, e.g.
	~/ooo-build-1.9.125/build/src680-m125/

	d) Rebuild OpenOffice source code with environment variable "TIMELOG" defined. APPR makes use of
	   RTL log feature and depends on this environment variable.
		export TIMELOG=TRUE
		make/build

Profiling with APPR
====================
Use ./appr --help for invocation options

For example:

./appr -t ../ooo-install/program/soffice.bin -p LoadFile ../testdocs/test.odt --enable=vtune,strace

	a) enables VTune sampling and strace profiling
	b) starts up the specified Openoffice executable
	c) loads the test.odt file
	d) and saves the log and results in the ./logs directory
